X User Tools

home *** CD-ROM | disk | FTP | other *** search

/ X User Tools / X User Tools (O'Reilly and Associates)(1994).ISO / sun4c / archive / tcltk.z / tcltk / man / cat3 / ParseArgv.3 < prev next >

Wrap

Text File | 1994-09-20 | 19.0 KB | 529 lines

Tk_ParseArgv(3) Tk Library Procedures _________________________________________________________________ NAME Tk_ParseArgv - process command-line options SYNOPSIS #include <tk.h> int Tk_ParseArgv(_i_n_t_e_r_p, _t_k_w_i_n, _a_r_g_c_P_t_r, _a_r_g_v, _a_r_g_T_a_b_l_e, _f_l_a_g_s) ARGUMENTS Tcl_Interp *_i_n_t_e_r_p (in) Interpreter to use for returning error mes- sages. Tk_Window _t_k_w_i_n (in) Window to use when argu- ments specify Tk options. If NULL, then no Tk options will be processed. int _a_r_g_c_P_t_r (in/out) Pointer to number of arguments in argv; gets modified to hold number of unprocessed arguments that remain after the call. char **_a_r_g_v (in/out) Command line arguments passed to main program. Modified to hold unpro- cessed arguments that remain after the call. Tk_ArgvInfo *_a_r_g_T_a_b_l_e (in) Array of argument descriptors, terminated by element with type TK_ARGV_END. int _f_l_a_g_s (in) If non-zero, then it specifies one or more flags that control the parsing of arguments. Different flags may be OR'ed together. The flags currently defined are TK_ARGV_DONT_SKIP_FIRST_ARG, TK_ARGV_NO_ABBREV, TK_ARGV_NO_LEFTOVERS, and TK_ARGV_NO_DEFAULTS. Tk 1 Tk_ParseArgv(3) Tk Library Procedures _________________________________________________________________ DESCRIPTION Tk_ParseArgv processes an array of command-line arguments according to a table describing the kinds of arguments that are expected. Each of the arguments in _a_r_g_v is processed in turn: if it matches one of the entries in _a_r_g_T_a_b_l_e, the argument is processed according to that entry and discarded. The arguments that do not match anything in _a_r_g_T_a_b_l_e are copied down to the beginning of _a_r_g_v (retaining their origi- nal order) and returned to the caller. At the end of the call Tk_ParseArgv sets *_a_r_g_c_P_t_r to hold the number of argu- ments that are left in _a_r_g_v, and _a_r_g_v[*_a_r_g_c_P_t_r] will hold the value NULL. Normally, Tk_ParseArgv assumes that _a_r_g_v[_0] is a command name, so it is treated like an argument that doesn't match _a_r_g_T_a_b_l_e and returned to the caller; however, if the TK_ARGV_DONT_SKIP_FIRST_ARG bit is set in _f_l_a_g_s then _a_r_g_v[_0] will be processed just like the other elements of _a_r_g_v. Tk_ParseArgv normally returns the value TCL_OK. If an error occurs while parsing the arguments, then TCL_ERROR is returned and Tk_ParseArgv will leave an error message in _i_n_t_e_r_p->_r_e_s_u_l_t in the standard Tcl fashion. In the event of an error return, *_a_r_g_v_P_t_r will not have been modified, but _a_r_g_v could have been partially modified. The possible causes of errors are explained below. The _a_r_g_T_a_b_l_e array specifies the kinds of arguments that are expected; each of its entries has the following structure: typedef struct { char*_k_e_y; int _t_y_p_e; char*_s_r_c; char*_d_s_t; char*_h_e_l_p; } Tk_ArgvInfo; The _k_e_y field is a string such as ``-display'' or ``-bg'' that is compared with the values in _a_r_g_v. _T_y_p_e indicates how to process an argument that matches _k_e_y (more on this below). _S_r_c and _d_s_t are additional values used in process- ing the argument. Their exact usage depends on _t_y_p_e, but typically _s_r_c indicates a value and _d_s_t indicates where to store the value. The char * declarations for _s_r_c and _d_s_t are placeholders: the actual types may be different. Lastly, _h_e_l_p is a string giving a brief description of this option; this string is printed when users ask for help about command-line options. Tk 2 Tk_ParseArgv(3) Tk Library Procedures When processing an argument in _a_r_g_v, Tk_ParseArgv compares the argument to each of the _k_e_y's in _a_r_g_T_a_b_l_e. Tk_ParseArgv selects the first specifier whose _k_e_y matches the argument exactly, if such a specifier exists. Otherwise Tk_ParseArgv selects a specifier for which the argument is a unique abbreviation. If the argument is a unique abbreviation for more than one specifier, then an error is returned. If there is no matching entry in _a_r_g_T_a_b_l_e, then the argument is skipped and returned to the caller. Once a matching argument specifier is found, Tk_ParseArgv processes the argument according to the _t_y_p_e field of the specifier. The argument that matched _k_e_y is called ``the matching argument'' in the descriptions below. As part of the processing, Tk_ParseArgv may also use the next argument in _a_r_g_v after the matching argument, which is called ``the following argument''. The legal values for _t_y_p_e, and the processing that they cause, are as follows: TK_ARGV_END Marks the end of the table. The last entry in _a_r_g_T_a_b_l_e must have this type; all of its other fields are ignored and it will never match any arguments. TK_ARGV_CONSTANT _S_r_c is treated as an integer and _d_s_t is treated as a pointer to an integer. _S_r_c is stored at *_d_s_t. The matching argument is discarded. TK_ARGV_INT The following argument must contain an integer string in the format accepted by strtol (e.g. ``0'' and ``0x'' prefixes may be used to specify octal or hexadecimal numbers, respectively). _D_s_t is treated as a pointer to an integer; the following argument is converted to an integer value and stored at *_d_s_t. _S_r_c is ignored. The matching and following arguments are discarded from _a_r_g_v. TK_ARGV_FLOAT The following argument must contain a floating-point number in the format accepted by strtol. _D_s_t is treated as the address of an double-precision floating point value; the following argument is converted to a double-precision value and stored at *_d_s_t. The match- ing and following arguments are discarded from _a_r_g_v. TK_ARGV_STRING In this form, _d_s_t is treated as a pointer to a (char *); Tk_ParseArgv stores at *_d_s_t a pointer to the fol- lowing argument, and discards the matching and follow- ing arguments from _a_r_g_v. _S_r_c is ignored. Tk 3 Tk_ParseArgv(3) Tk Library Procedures TK_ARGV_UID This form is similar to TK_ARGV_STRING, except that the argument is turned into a Tk_Uid by calling Tk_GetUid. _D_s_t is treated as a pointer to a Tk_Uid; Tk_ParseArgv stores at *_d_s_t the Tk_Uid corresponding to the follow- ing argument, and discards the matching and following arguments from _a_r_g_v. _S_r_c is ignored. TK_ARGV_CONST_OPTION This form causes a Tk option to be set (as if the option command had been invoked). The _s_r_c field is treated as a pointer to a string giving the value of an option, and _d_s_t is treated as a pointer to the name of the option. The matching argument is discarded. If _t_k_w_i_n is NULL, then argument specifiers of this type are ignored (as if they did not exist). TK_ARGV_OPTION_VALUE This form is similar to TK_ARGV_CONST_OPTION, except that the value of the option is taken from the follow- ing argument instead of from _s_r_c. _D_s_t is used as the name of the option. _S_r_c is ignored. The matching and following arguments are discarded. If _t_k_w_i_n is NULL, then argument specifiers of this type are ignored (as if they did not exist). TK_ARGV_OPTION_NAME_VALUE In this case the following argument is taken as the name of a Tk option and the argument after that is taken as the value for that option. Both _s_r_c and _d_s_t are ignored. All three arguments are discarded from _a_r_g_v. If _t_k_w_i_n is NULL, then argument specifiers of this type are ignored (as if they did not exist). TK_ARGV_HELP When this kind of option is encountered, Tk_ParseArgv uses the _h_e_l_p fields of _a_r_g_T_a_b_l_e to format a message describing all the valid arguments. The message is placed in _i_n_t_e_r_p->_r_e_s_u_l_t and Tk_ParseArgv returns TCL_ERROR. When this happens, the caller normally prints the help message and aborts. If the _k_e_y field of a TK_ARGV_HELP specifier is NULL, then the specifier will never match any arguments; in this case the specifier simply provides extra documentation, which will be included when some other TK_ARGV_HELP entry causes help information to be returned. TK_ARGV_REST This option is used by programs or commands that allow the last several of their options to be the name and/or options for some other program. If a TK_ARGV_REST argument is found, then Tk_ParseArgv doesn't process Tk 4 Tk_ParseArgv(3) Tk Library Procedures any of the remaining arguments; it returns them all at the beginning of _a_r_g_v (along with any other unprocessed arguments). In addition, Tk_ParseArgv treats _d_s_t as the address of an integer value, and stores at *_d_s_t the index of the first of the TK_ARGV_REST options in the returned _a_r_g_v. This allows the program to distinguish the TK_ARGV_REST options from other unprocessed options that preceeded the TK_ARGV_REST. TK_ARGV_FUNC For this kind of argument, _s_r_c is treated as the address of a procedure, which is invoked to process the following argument. The procedure should have the fol- lowing structure: int _f_u_n_c(_d_s_t, _k_e_y, _n_e_x_t_A_r_g) char *_d_s_t; char *_k_e_y; char *_n_e_x_t_A_r_g; { } The _d_s_t and _k_e_y parameters will contain the correspond- ing fields from the _a_r_g_T_a_b_l_e entry, and _n_e_x_t_A_r_g will point to the following argument from _a_r_g_v (or NULL if there aren't any more arguments left in _a_r_g_v). If _f_u_n_c uses _n_e_x_t_A_r_g (so that Tk_ParseArgv should discard it), then it should return 1. Otherwise it should return 0 and TkParseArgv will process the following argument in the normal fashion. In either event the matching argu- ment is discarded. TK_ARGV_GENFUNC This form provides a more general procedural escape. It treats _s_r_c as the address of a procedure, and passes that procedure all of the remaining arguments. The procedure should have the following form: int _g_e_n_f_u_n_c(_d_s_t, _i_n_t_e_r_p, _k_e_y, _a_r_g_c, _a_r_g_v) char *_d_s_t; Tcl_Interp *_i_n_t_e_r_p; char *_k_e_y; int _a_r_g_c; char **_a_r_g_v; { } The _d_s_t and _k_e_y parameters will contain the correspond- ing fields from the _a_r_g_T_a_b_l_e entry. _I_n_t_e_r_p will be the Tk 5 Tk_ParseArgv(3) Tk Library Procedures same as the _i_n_t_e_r_p argument to Tcl_ParseArgv. _A_r_g_c and _a_r_g_v refer to all of the options after the matching one. _G_e_n_f_u_n_c should behave in a fashion similar to Tk_ParseArgv: parse as many of the remaining arguments as it can, then return any that are left by compacting them to the beginning of _a_r_g_v (starting at _a_r_g_v[0]). _G_e_n_f_u_n_c should return a count of how many arguments are left in _a_r_g_v; Tk_ParseArgv will process them. If _g_e_n_- _f_u_n_c encounters an error then it should leave an error message in _i_n_t_e_r_p->_r_e_s_u_l_t, in the usual Tcl fashion, and return -1; when this happens Tk_ParseArgv will abort its processing and return TCL_ERROR. FLAGS TK_ARGV_DONT_SKIP_FIRST_ARG Tk_ParseArgv normally treats _a_r_g_v[_0] as a program or command name, and returns it to the caller just as if it hadn't matched _a_r_g_T_a_b_l_e. If this flag is given, then _a_r_g_v[_0] is not given special treatment. TK_ARGV_NO_ABBREV Normally, Tk_ParseArgv accepts unique abbreviations for _k_e_y values in _a_r_g_T_a_b_l_e. If this flag is given then only exact matches will be acceptable. TK_ARGV_NO_LEFTOVERS Normally, Tk_ParseArgv returns unrecognized arguments to the caller. If this bit is set in _f_l_a_g_s then Tk_ParseArgv will return an error if it encounters any argument that doesn't match _a_r_g_T_a_b_l_e. The only excep- tion to this rule is _a_r_g_v[_0], which will be returned to the caller with no errors as long as TK_ARGV_DONT_SKIP_FIRST_ARG isn't specified. TK_ARGV_NO_DEFAULTS Normally, Tk_ParseArgv searches an internal table of standard argument specifiers in addition to _a_r_g_T_a_b_l_e. If this bit is set in _f_l_a_g_s, then Tk_ParseArgv will use only _a_r_g_T_a_b_l_e and not its default table. EXAMPLE Here is an example definition of an _a_r_g_T_a_b_l_e and some sample command lines that use the options. Note the effect on _a_r_g_c and _a_r_g_v; arguments processed by Tk_ParseArgv are elim- inated from _a_r_g_v, and _a_r_g_c is updated to reflect reduced number of arguments. /* * Define and set default values for globals. */ Tk 6 Tk_ParseArgv(3) Tk Library Procedures int debugFlag = 0; int numReps = 100; char defaultFileName[] = "out"; char *fileName = defaultFileName; Boolean exec = FALSE; /* * Define option descriptions. */ Tk_ArgvInfo argTable[] = { {"-X", TK_ARGV_CONSTANT, (char *) 1, (char *) &debugFlag, "Turn on debugging printfs"}, {"-N", TK_ARGV_INT, (char *) NULL, (char *) &numReps, "Number of repetitions"}, {"-of", TK_ARGV_STRING, (char *) NULL, (char *) &fileName, "Name of file for output"}, {"x", TK_ARGV_REST, (char *) NULL, (char *) &exec, "File to exec, followed by any arguments (must be last argument)."}, {(char *) NULL, TK_ARGV_END, (char *) NULL, (char *) NULL, (char *) NULL} }; main(argc, argv) int argc; char *argv[]; { ... if (Tk_ParseArgv(interp, tkwin, &argc, argv, argTable, 0) != TCL_OK) { fprintf(stderr, "%s\n", interp->result); exit(1); } /* * Remainder of the program. */ } Note that default values can be assigned to variables named in _a_r_g_T_a_b_l_e: the variables will only be overwritten if the particular arguments are present in _a_r_g_v. Here are some example command lines and their effects. prog -N 200 infile # just sets the numReps variable to 200 prog -of out200 infile # sets fileName to reference "out200" prog -XN 10 infile # sets the debug flag, also sets numReps In all of the above examples, _a_r_g_c will be set by Tk_ParseArgv to 2, _a_r_g_v[0] will be ``prog'', _a_r_g_v[1] will be ``infile'', and _a_r_g_v[2] will be NULL. Tk 7 Tk_ParseArgv(3) Tk Library Procedures KEYWORDS arguments, command line, options Tk 8